.TH ESP "1" "November 2014" "esp" "User Commands"
.SH NAME
esp \- ESP Application Generator for Server-Side Web Applications.
.SH SYNOPSIS
.B esp
    \fB--cipher cipher\fR
    \fB--database DB\fR
    \fB--force\fR
    \fB--genlink slink.c\fR
    \fB--home dir\fR
    \fB--keep\fR
    \fB--listen [ip:]port\fR
    \fB--log logFile:level\fR
    \fB--name appName\fR
    \fB--noupdate\fR
    \fB--nodeps\fR
    \fB--optimized\fR
    \fB--quiet\fR
    \fB--platform [path/]os-arch-profile\fR
    \fB--rebuild\fR
    \fB--routeName name\fR
    \fB--routePrefix prefix\fR
    \fB--single\fR
    \fB--show\fR
    \fB--static\fR
    \fB--symbols\fR
    \fB--table name\fR
    \fB--trace traceFile:level\fR
    \fB--verbose\fR
    \fB--why\fR
    \fBcommands ...\fR
.SH ""
.B Commands:
    esp clean
    esp compile [pathFilters...]
    esp config
    esp edit key[=value]
    esp generate controller name [action [, action] ...]
    esp generate migration description model [field:type ...]
    esp generate scaffold model [field:type ...]
    esp generate table name model [field:type ...]
    esp init [name [version]]
    esp migrate [forward|backward|NNN]
    esp mode [debug|release|otherMode]
    esp role [add|remove] rolename
    esp [run] [ip]:[port]
    esp user [add|compute] username password roles...
    esp user [remove|show] username 
.SH DESCRIPTION
The \fBesp\fR command generates, manages and runs ESP web applications. It includes a full HTTP/1.1 web server to 
host your application and can generate ESP skeletons, controllers, database tables, and scaffolds.
.PP
The esp command will create directories and generate configuration and source code files that can then be manually 
edited as required.  ESP is intelligent and will not overwrite existing files, so you can safely edit 
and regenerate without losing your changes. You can overwrite your changes if you wish to by using 
the \fB--force\fR switch.
.PP
.SH RUNNING ESP
To run ESP to serve documents from the current directory, type:
.RS 5
 \fBesp\fR
 # or
 \fBesp run\fR
.RE 5

.SH GENERATING APPLICATIONS
To start a new web application, create a directory named for the application. Then from that directory
run \fBpak\fR to install the required supporting packs. For example:

.RS 5
 \fBmkdir blog\fR
 \fBcd blog\fR
 \fBpak install esp-html-skeleton\fR
.RE
.PP
This will will create a set of directories that have the following meaning: 

.RS 5
 documents           - Public client web content
 documents/assets    - Images and assets
 documents/css       - Client CSS and Less style sheets
 documents/index.esp - Home web page
 paks                - Extension packs
 db                  - Databases and scripts
 generate            - Template files used when generating
.RE
.PP
Other directories will be created as needed:
.RS 5
 cache            - Cache directory for compiled content
 db/migrations    - Databases migration modules
 controllers      - Server side controllers
 src              - Server side main source code
.RE
.PP
Most of these directories are initially empty, but may be used over time. ESP follows conventions
where specific files are stored. This greatly simplifies configuring a web application.
.PP

Packs are modules of functionality for ESP applications that are packaged using the
Pak utility (see https://www.embedthis.com/pak).
Packs may depend on other packs so that installing a top level pack
may install other required packs. For example: generating the "esp-html-skeleton" pack will
also install: esp-mvc, exp-less, and other paks.
.PP
See https://www.embedthis.com/catalog/ for a list of packs.

.SH GENERATING MIGRATIONS
Migrations are generated code modules that manage portions of the database. Migrations are used to create tables, 
initialize with test data and optionally destroy tables. Migrations are typically generated and then hand-edited to 
include relevant initialization or test data. Migrations are useful to quickly recreate the database with the required
tables and data.
.RS 5

 \fBesp generate migration DESCRIPTION TABLE [field:type ...]\fR
.RE

The DESCRIPTION is used to name the migration which is created in the \fBdb/migrations\fR directory. A migration 
is given a unique ordered sequence number and the description is appended to this number. The description is mapped
where spaces are changed to "_" characters. When migrations are run, they are run in sequence number order.
.PP
If field:type values are supplied, the database migration will include code to create a column for each 
specified field of the requested type. The valid database types are: blob, boolean, date, float, integer, string, 
and text.

.SH GENERATING TABLES
To generate a database table without creating a migration:
.RS 5

 \fBesp generate table TABLE [field:type ...]\fR
.RE

.SH GENERATING CONTROLLERS
Controllers are the primary mechanism for responding to client requests. 
To generate a controller, 
run:
.RS 5

 \fBesp generate controller NAME [actions...]\fR
.RE
.PP
This will create a controller of the requested name. It will create a controller source file in the \fBcontrollers\fR
directory. If action names are requested, the controller source will define an action method for each
name. You can edit the controller source to meet your needs. It will not be overwritten unless you specify the
--force switch.

.SH GENERATING SCAFFOLDS
.PP
A scaffold is a generated controller, database migration, client-side controller and set of views that provides add, edit 
and list functionality for the database table.
Scaffolds are useful to quickly generate chunks of the application and prototype web pages and actions for 
managing a database table.
To generate a scaffold:
.RS 5

 \fBesp generate scaffold MODEL [field:type ...]\fR
.RE
.PP
This will create a scaffold for the specified database table and will generate a controller of the same name.
.PP
If field:type values are supplied, a database migration will be created with code to create a column for each 
specified field of the requested type. The valid database types are: blob, boolean, date, float, integer, string,
and text. The migration will use the name "create_scaffold_MODEL" and will be created under 
the \fBdb/migrations\fR direcvtory.
.PP
The scaffold will include an edit action and view page that provides add and edit capability. The list action and view, 
provides the ability to list the table rows and select an entry to edit.
.PP
If the --singleton switch is ues, the controller will be generated for a singleton resource and will not have a list
action. 

.SH COMPILING
ESP compiles controllers and ESP pages native code shared libraries. These are then loaded and
run by ESP in response to incoming client requests. Code is compiled only once but can be run many times to
service incoming requests.
.PP
In development mode, ESP will automatically compile the relevant portions of the application if the source code
is modified. It can intelligently recompile controllers and ESP pages. However, you can also explicilty recompile 
portions or the complete appliction via the esp command.
.PP
ESP can recompile everything via:

.RS 5
 \fBesp compile\fR.
.RE

This will re-compile all ESP resources.
.PP
ESP also provides options for you to individually compile controllers and ESP pages. To recompile named pages or controllers:
.RS 5

 \fBesp compile path/*.esp...\fR.

The arguments after "compile" are pathname filters. These are resolved relative to the current directory. Only items
matching the filter pathnames are compiled.

.RE
.PP
To compile the entire application and produce a single combined shared library file, set the "esp.combine" 
property in the esp.json file, to true.
.RS 5

.SH AUTHENTICATION
ESP can use the system password database or it can define passwords in the esp.json or in an application database.
To define passwords in the esp.json, use:

 \fBesp user add username password roles...\fR

To define authentication roles, use:

  \fBesp role add abilities...\fR

.SH CROSS-COMPILING
To compile for a target system of a different architecture, you must specify the target. 
To do this, use the -platform switch to specify the target architecture. Specify the path to the platform directory
in the Appweb source code built for that platform.

.RS 5
\fbesp -platform /home/dev/linux-arm-debug compile
.RE

.SH MODE
The \fBesp mode\fR command will retrieve and display the "esp.mode" property.
The \fBesp mode debug\fR command will modify the "esp.mode" property and set it to the "debug" value.
The \fBesp release\fR command will set the esp.mode to "release".

.SH RUNNING
.PP
To run your application:
.RS 5

 \fBesp run\fR
.SH CLEANING
To clean all generated module files:
.RS 5
 \fBesp clean\fR
.RE

.SH MIGRATIONS
Migration files can be run via the \fBesp migrate\fR command. With no other parameters, the command will run
all migrations that have not yet been applied to the database. You can also use \fBesp migrate forward\fR to
apply apply the next unapplied migration. Similarly \fBesp migrate backward\fR will reverse the last applied
migration. You can also use \fBesp migrate NNN\fR to migrate forward or backward to a specific migration, where NNN
is the migration sequence number at the start of the migration file name.
.PP

.SH COMMANDS
.PP 
esp has the following command usage patterns:

.RS 5
 esp clean
 esp compile
 esp compile controllers name
 esp compile path/*.esp
 esp generate app name
 esp generate controllers name [action [, action] ...]
 esp generate scaffold model [field:type [, field:type] ...]
 esp generate table name model [field:type [, field:type] ...]
 esp run
 esp run 4000
 esp mode debug
 esp init appName version
.RE
.PP

.SH OPTIONS
.PP
.TP 6
\fB\--cipher cipher\fR
Password cipher to use. Set to "md5" or "blowfish".
.TP 6
\fB\--database Database provider\fR
Use the specified database provider. Set to "mdb" or "sdb" for SQLite.
.TP 6
\fB\--force\fR
Overwrite existing files. ESP normally will not overwrite existing files. This is to preserve user changes to 
previously generated files.
.TP 6
\fB\--home dir\fR
Change the current working directory before beginning processing.
.TP 6
\fB\--keep\fR
Keep intermediate source files in the cache directory. This overrides the 
ejs.json "keep" setting.
.TP 6
\fB\--listen [ip:]port\fR
Define the listening endpoint address. This will be used when generating an application. The value
will be patched into the generated esp.json configuration file.
.TP 6
\fB\--log logFile:level\fR
Specify a file to log messages.  The syntax is: \fB"--log logName[:logLevel]"\fR.             
Level 3 will trace the request and response headers. 
.TP 6
\fB\--name AppName\fR
Set the ESP application name. Defaults to the name of the directory containing the application.
.TP 6
\fB\--noupdate\fR
Do not update esp.json.
.TP 6
\fB\--optimize\fR
Compile optimized without debug symbols. 
.TP 6
\fB\--quiet\fR
Suppress diagnostic trace to the console.
.TP 6
\fB\--platform [path/]os-arch-profile\fR
Target platform configuration to build for and directory containing esp objects and libraries for the target platform. 
If a path is supplied, the specified platform directory is used.  Otherwise, esp searches from the current directory 
upwards for a parent platform directory.
.TP 6
\fB\--rebuild\fR
Force a recompile of all items when used with the compile command. 
When used with migrate, this will recreate the database and apply all migrations.
.TP 6
\fB\--route pattern\fR
This selects the route by pattern that will be used for the ESP configuration. 
.TP 6
\fB\--routePrefix prefix\fR
This selects the route by prefix that will be used for the ESP configuration. 
If the route prefix does not match, the first portion of the route pattern is tested against the requested prefix. 
.TP 6
\fB\--single\fR
Generate a controller for a singleton resource instead of a group of resources. A singleton controller omits a list
action.
.TP 6
\fB\--show\fR
Display the route table to the console.
.TP 6
\fB\--static\fR
Use static linking when building ESP applications. This causes esp to create archive libraries instead of shared libraries.
.TP 6
\fB\--symbols\fR
Compile for debug with symbols. 
.TP 6
\fB\--table name\fR
Override the database table name when generating tables, migrations or scaffolds. This is useful to request a plural 
version of the model name. Alternatively, specify the model name when generating the scaffold, table or migration 
with the desired plural suffix. For example: "-s" or "-ies".
.TP 6
\fB\--trace traceFile:level\fR
Specify a file for trace messages.  The syntax is: \fB"--trace traceName[:traceLevel]"\fR.             
Level 3 will trace the request and response headers. 
.TP 6
\fB\--verbose\fR or \fB\-v\fR
Run in verbose mode and trace actions to the console.
.TP 6
\fB\--why\fR or \fB\-w\fR
Explain why a resource was or was not compiled.
.PP
.SH "REPORTING BUGS"
Report bugs to dev@embedthis.com.

.SH COPYRIGHT
Copyright \(co Embedthis Software. Embedthis ESP is a trademark of Embedthis Software.

.br
